#$Header: /cvsroot/quark/source/3d\040code\040review.txt,v 1.3 2003/09/06 02:22:11 tiglari Exp $


AddTo3DScene:

AddTo3DScene is the method of map objects whereby the map structure
builds the 3d scene.  The real work is done by methods such as
TFace.AddTo3DScene in prog/QkMapPoly.pas [tig: what is the correct name for
a subclass's implementation of a virtual method?]; we see that
the workhorse line is:

        CurrentMapView.Scene.AddPolyFace(P);

CurrentMapView is a global variable of type TPyMapView defined by
this line of python/PyMapView.pas:

 CurrentMapView : TPyMapView = TPyMapView(-1);

A TPyMapView is a subclass of TScrollBox, I presume the -1 is setting
its owner to nothing [tig: check this].  For some reason, Scene is a property
whose read method is FScene, whose value is a TSceneObject.

TSceneObject:

TSceneObject defined in 3dfx/EdSceneObject.pas, with subclasses:

  3dfx\Ed3DFX.pas(123): T3DFXSceneObject = class(TSceneObject)
  3dfx\EdOpenGL.pas(107): TGLSceneBase = class(TSceneObject)
  3dfx\EdDirect3D.pas(60): TDirect3DSceneObject = class(TSceneObject)

The first is the class for the software and 3dfx 3d textured
views, the second of the OGL one, and the last is the start of
an unfinished projet to produce a 3dfx view; the appropriate
constructors are called by python/PyMapView:TPyMapView.NeedScene.

EdSceneObject.pas:  Seems to be divided into two sections, one concerned
with TSceneObject, the other with TTexture Manager.  The interesting
non-virtual method is BuildScene, which is very big - Armin seems
to often have gone for extremely long functions, which are supposed to
be bad style, so perhaps we could think about breaking this  one
up into intelligible bits?

An important type in 3d scene building is PSurface, defined in
prog/QkMapPoly.pas, which defines a visible polyhedron face.  It
is a pointer to a TSurface, defined as follows:

TSurface = record
             Source: TTreeMap;
             F: TFace;
             NextF: PSurface;   { linked list of PSurfaces for a given face }
             prvVertexCount: Integer;
             prvVertexTable: TFVertexTable;
            end;

Each face has a linked list of PSurfaces because of face-sharing. F is
used to get info about the texture-name, etc., Source isn't used by
this module.  The PSurfaces are rebuilt by code in QkMapPoly.pas.

The AddSurfaceRef sub-procedure of BuildScene adds a surface to a master-list
of surfaces, TSceneObject.FListSurfaces, accesible also as read-property
ListSurfaces. Need to  understand BuildScene to see what this does.

Questions about TSceneObject:

  how does BuildScene work?
  what is SetColor do for?
  what is the purpose of ChangeQuality?

BuildScene:

  If a 3d window is open, gets called every time anything happens to the
   views.  This seems excessive, for example for a selection event very little
   gets changed.

  1.  some initializations:
         Held over from previous BuildScene:
           TextureManager
         Reinitialized:
           TexNames list
           FlistSurfaces - done via linked list freeing, maybe a slowdown factor?
           nVertexList and nVertexList2

  2.  scan the map objects and build the TexNames list, which gives
        information about surfaces indexed by the TexNames, and
        also add this information to the FlistSurfaces list.
        
       Problem: the info specifyies how much info is needed to store
       the vertexes of the faces using the texture, but no info about
       those vertexes seems to be recorded.
       

  3.  rebuild the old textures, note how many new ones needed.
        Q: what does building do?
  
  4.  free old textures no longer needed
  
  5.  load and build new textures
  
  6.  build a lot of stuff
  
  7.  for each face, load a lot of stuff into the appropriate
        surf3d element [some of it looks like texture coordinates]
  
  8.  ditto for models, sprites and beziers
        lots of rather repetitive-looking code.
        
  9.  and a bit of final cleanup.
  
More understanding of what goes on it steps 7-8 is needed here.

  
#$Log: 3d\040code\040review.txt,v $
#Revision 1.3  2003/09/06 02:22:11  tiglari
#BuildScene - first go at overview
#
#Revision 1.2  2003/09/02 23:35:13  tiglari
#More on EdSceneObject.pas, also some questions added
#
#Revision 1.1  2003/09/02 00:01:43  tiglari
#started by tiglari, some points for more work bracketted as [tig: ...]
#